BCI NET

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET / BCI NET Dec 94.iso / archives / utilities / wb / buttonmenu_120.lha / buttonmenu / ButtonMenu.doc < prev next >

Wrap

Text File | 1994-09-06 | 16.1 KB | 435 lines

BUTTONMENU V1.20 CONTENTS ========================= Introduction Disclaimer Copyright Distribution Acknowledgements Compatibility Requirements Getting Started Reference How To Create a Button Menu How To Use a Button Menu Keyboard Shortcuts Height Confusion What to do if the items won't fit Limitations ButtonMenu Creator Menus ButtonMenu Creator Gadgets Contacting the author History INTRODUCTION ============ ButtonMenu allows Kickstart 2.0 (or higher) owners to create menus in the form of a window full of GadTools buttons. Two programs are provided: one to allow you to create the menu and one which runs the menu. It is then possible to run your menu from a startup-sequence, for example. The GUI for the creator was designed to use Topaz 8, but it will adapt to the current screen font if it is not too big. An added bonus is the ability to load ButtonMenu from within ButtonMenu from within ButtonMenu and so on... This means you can nest menus to create complicated menu systems. DISCLAIMER ========== I cannot be held liable if this program causes you to lose valuable data, nor can I be blamed if this program causes any other problems with your system. Any problems are entirely the user's responsibility. COPYRIGHT ========= ButtonMenu V1.20 - written with DICE C (2.07.56R) on an A600. (c) Oliver Roberts, 1994 ButtonMenu is public domain and the copyright remains with the author. DISTRIBUTION ============ ButtonMenu is freely distributable providing none of the distributed files are changed in any way, ButtonMenu is not sold for profit and it is not included on any disks that are sold solely for profit. If ButtonMenu is to be sold for profit, permission must be obtained from me, the author (Oliver Roberts). Included in the above are magazine coverdisks - let me know if you wish to use ButtonMenu menus on the disk(s). For following files MUST be distributed together if the Creator is to be included: ButtonMenu (ButtonMenu Creator) ButtonMenu.info ButtonMenu.doc (Document) ButtonMenu.doc.info ButtonMenu.guide (Document in hypertext format) ButtonMenu.guide.info BMX (ButtonMenu Executor) BMX.info CHANGES (Recent changes) README (Additional Information) reqtools.library (KS2.0 V38 - Needed for Creator only) If you just want to distribute your created menu then you can distribute the BMX program without the files above, if desired. ACKNOWLEDGEMENTS ================ Reqtools.library (c) 1991-1994 Nico Francois The GUI for the Creator was mainly created with: GadToolsBox V2.0b (c) 1991-1993 Jaba Development Thanks to Rick Hughes for giving some ideas for new features, and for the donation he made. COMPATIBILITY ============= ButtonMenu has been tested on an A600 with KS2.05 and KS3.0 using NTSC/PAL, chip/fake fast, chip configurations. ButtonMenu is fully OS-Legal, it should work on ANY Amiga with Kickstart 2.0 or higher! REQUIREMENTS ============ Any Amiga with Kickstart 2.0 (V36) or higher. NTSC / PAL To run the Creator you will need these disk based libraries in the LIBS: drawer on you boot disk or HD. diskfont.library (V36 or higher) reqtools.library (V38 or higher) To run the Executor you do NOT need "reqtools.library" in the LIBS: drawer, but if you are not using a ROM font (ie Topaz 8 or Topaz 9) for the menu you will need "diskfont.library" if the font has not already been loaded into RAM by another program. GETTING STARTED =============== First make sure you have the libraries mentioned in the REQUIREMENTS section installed in your LIBS: drawer on you HD or boot disk. From Workbench -------------- Double-click on the ButtonMenu icon. From the Shell -------------- Type `ButtonMenu' at the prompt. There are no command line options at present. How to Create a Button Menu =========================== Making a menu is simple with ButtonMenu. Just enter the items you wish to be displayed to the user and the AmigaDOS command lines. Keyboard shortcuts can be assigned to each item as well (read the Keyboard Shortcuts section for full details). Entering the commands is made simplier by providing a file requester: just click on the gadget next to the command text gadget and select the file you want to be run when the user clicks on the button. You can also ask for the command to be run in the background (uses the AmigaDOS `run' command). Then select the font you wish to use for the buttons, the size of the window and the title for the window. Then select 'Save' from the menu. How to Use a Button Menu ======================== Type `BMX <filename>' at a DOS prompt and the menu will appear. Where <filename> is the name of a ButtonMenu datafile which you have previously saved (defaults to `BM.dat'). The menu should now appear. Alternatively, you may double click on a ButtonMenu datafile icon and the menu will be displayed. Now just click on the button (or use a keyboard shortcut) to run the corresponding commands, and click the close gadget when you have finished. Keyboard Shortcuts ================== You can specify keyboard shortcuts for each item, if you want. You are not allowed to use the same key for more than one item (ButtonMenu will tell you if you do). Pressing any of the keys a..z in your generated menu will have exactly the same effect as keys A..Z, thus case is not important (unless you have the doc function enabled!) There are a few ways of denoting the keyboard shortcut in the item text. For example, with shortcut `B' you could have: [B]uttonMenu or (B)uttonMenu or {B}uttonMenu etc... But the preferred way is to use an underscore character underneath the letter to be emphasized - like most new Amiga applications. You do this in ButtonMenu by putting an `_' character directly before the character to be underscored. For example: "_ButtonMenu" produces ButtonMenu - Therefore, only use the underscore character for this purpose - using more than one won't make any difference as the leftmost ones will be ignored and not displayed. Height Confusion ================ Some people may find the way the Height of the menu window is calculated confusing - or uninteresting! So for users who want to know why the height is what it is, here is a little (well... long) explanation: "The Amiga OS will always use the screen's default font (set in Workbench preferences) for the text in the title bars for each window opened. This means that the size of the title bar is variable when running the menu with `BMX' and it is inconvenient to keep the height of the window constant - the calculations in the ButtonMenu Creator would also have to be used in the `BMX' program which would make the program nearly as large as the creator, and would create incompatibilities with different systems. I wanted the menu to be displayed as quickly as possible with the smallest possible program. So, you are asked to enter the maximum inner height for the window, which is the height of window excluding the title bar and bottom border. The `Calculated Total Height' gadget will display an estimate for the total height of the window, using the current screen font. Included is a `Height Adjust' feature. This will alter the height further, by removing any blank lines that will not be used giving a slightly tidier menu. To do this though, the `Calculated Total Height' is calculated as before, but with the smallest possible height. " What to do if the items won't fit ================================= If you have the Adjust Height feature enabled, or are trying to save your menu, and get any error message saying that the item(s) won't fit in the window, then here are the possible causes/solutions: Causes ------ * The text length of one of the items is too long (and/or longer than the width of the window) * The font is too large * The window is too small * Too many items Solutions (a bit obvious!) --------- * Shorten the length of the item texts * Select a smaller font * Enlarge the window * Delete some of the longer items Limitations =========== The only limitation to the menus you create is that there must be at least 1 item and no more than 100 items. If you need more items - let me know. ButtonMenu Creator Menus ======================== Project Help Settings New : Resets the creator by deleting all items. Warning: Make sure you have saved any wanted edits before selecting! Open : Load a ButtonMenu datafile which you have previously saved. Save : Save current edits back to the same file which you have just loaded. If this a new file, a file requester will be available for you to enter a new name. Save As: Save current edits backs to another file. Test : Display the menu which you have designed. This uses the external BMX program to load the menu - BMX must therefore be in the search path somewhere. About : Some copyright notes and version information. Quit : Quit ButtonMenu unconditionally. This menu provides some brief hints on how to use ButtonMenu, without having to look at the document you are reading now. Save Icons? : If you select this item, icons will be saved with your datafiles so that the menus can be started from Workbench with a click of a button. Save Settings: Save the current state of the Save Icons flag in the "s:ButtonMenu.config" file. ButtonMenu Creator Gadgets ========================== Item Gadgets - Main Secondary Function (optional) General Gadgets New Item : Add a new item to the menu, after the currently selected one (or the start if there are no items). Delete Item: Erase the currently selected menu item. Up : Move the currently selected item up the list. Down : Move the currently selected item down the list. Item Text : The text to be displayed on one of the menu buttons. If you put a `_' character in front of another character, ButtonMenu will denote that letter as the keyboard shortcut (you must also but this letter in the keyboard shortcut requester). DOS : The command to be executed when the corresponding menu Command button is clicked. This is to be in the same format as you would run it from the CLI manually. You can also select commands via a file requester, so you don't need to remember the exact filenames. Keyboard : Specifies an optional key that performs the same function Shortcut as clicking on the button on the finished menu. Run command: Tells the Amiga to run that command as a background task. in This does the same thing as `run >NIL: <command>' would background do, where <command> is the contents of the DOS Command gadget. This command is activated by the left mouse button or the keyboard shortcut on the final menu. Enable Doc : Tell ButtonMenu that you want this item to have a second Function function which will be activated by holding the right mouse button or shift key and then pressing the left mouse button or keyboard shortcut. Doc : In conjuntion with the Doc Reader gadget you may enter the Filename filename of the corresponding document. The filename will be loaded by the Doc Reader. However, you may specify no doc reader and enter an AmigaDOS commandline in this gadget - this provides maximum flexibility. Font Used : The font to be used for the item text on the menu buttons. For Items Click the Choose Font button to change the font. Title : Text to be displayed in the title bar of your menu - uses a separate font. Width : Width of the menu window (in pixels). Inner : The height of your window excluding the title bar and Height bottom border. Adjust : With this feature turned on, any blank lines at the bottom Height of your menu window will be removed by decreasing the height. Checks will also be made to see if your items will actually fit in the menu window with the dimension you have specified whenever you alter these, the font or the Item Text. With the feature off, these checks are only made when saving. Calculated: This is the estimated total height of your window including Total the borders. Assumes the screen font you will use for the Height menu will be the same as the current one - that is why it is an estimate. Centre : Makes the menu appear in the centre of your screen. Window Single : Allows only ONE choice to be made on the menu. After the Choice corresponding command has returned, the menu will close. Doc : This is an optional field which may be filled with the Reader intended command line of your preferred document reader (e.g "run c:ppmore"). This field will be used by the secondary functions of all items, if it is not empty. CONTACTING THE AUTHOR ===================== You can contact me via e-mail at this address: robeoy@essex.ac.uk Or via snail-mail, my permanent home address is: 30 Tillett Road Norwich Norfolk NR3 4BJ ENGLAND HISTORY ======= V1.20 - August 31 1994 ButtonMenu nows uses functions available in KS 2.0 (or higher) instead of the equivalent ANSI C functions. The has resulted in a drastic decrease in executable size for the BMX executor (about a 50% reduction). Added a "Test" option to the project menu in the creator which uses BMX to run the menu. Added Workbench support to BMX which allows ButtonMenus to be loaded via an icon. It then made sense to add a settings menu with a Save Icons option and a configuration file saved in s: . Changed the Adjust Height error handling slightly resulting in less annoying requesters (also corrected a spelling mistake in the error message). Added a zoom gadget to the menu windows that are created. Added an option to centre the ButtonMenu when it is opened. New option to allow ButtonMenus to act more like requesters (ie only one choice is allowed - then the window is closed automatically). Amigaguide documentation provided in addition to the standard text doc. Bug Fix: Removed a bug which caused gadgets in the window to be refreshed more than once - resulting in flickering. =========================================================================== V1.10 - August 15 1994 (BETA version - not publically released) Added a keyboard shortcut facility - datafiles changed accordingly, but old ones are still supported. Added an option to display docs as a secondary action. New-look menus when ButtonMenu is run on KS 3.0 or higher. Bug fixes: I discovered a bug concerning the 4 buttons underneath the item listview gadget. Now, the buttons are checked in addition to being disabled when appropriate. A possible bug in the Executor message handler - fixed. Not all the text strings were freed properly which sometimes gave memory failures (ie Memory Insane) - fixed this. =========================================================================== V1.00 - July 28 1994 First release.